home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / util / misc / dirdb.lha / DirDB.doc < prev    next >
Text File  |  1993-03-10  |  8KB  |  249 lines
  1. This archive contains my "Directory Database" suite.
  2.  
  3. Please note these programs ALL require 2.04 or greater. :-)
  4.  
  5.  Contents :
  6.  ~~~~~~~~
  7.  
  8. The programs contained are :
  9.  
  10.   MakeDirDB
  11.   FindDBEntry
  12.   DBEntry
  13.  
  14. Also contained in this archive is Jonas Petersson's 'upd' program,
  15. which is an ARexx 8SVX sample server, and some scripts to use the
  16. Directory Database with your sound samples.
  17.  
  18.  
  19.  Purpose :
  20.  ~~~~~~~
  21.  
  22. These programs make and search databases created from Amiga directory
  23. trees. It is much faster to search one of these databases for a file,
  24. than it is to search the filesystem. Also, you can use these programs
  25. to do something with all the files which match a pattern, or with
  26. random files.
  27.  
  28.  
  29.  Uses :
  30.  ~~~~
  31.  
  32.  - Finding a file, when only part of its name is known
  33.  - Choosing a file at random
  34.   ++ Playing a random sound sample, either from a script (see the
  35.      examples), by a hot key (using FKey and the scripts) or
  36.      a cron program (and the scripts). My amiga plays a random
  37.      sound sample every quarter hour, between reasonable hours,
  38.      to keep me awake. Look for CyberCron.
  39.   ++ Choosing a random background picture (for WB3.0 or via NickPrefs).
  40.      1. Set up a directory of background images
  41.      2. Make a (hard) link to one of them,
  42.       eg. "MakeLink sys:prefs/presets/BGPic.pre sys:wbpics/Maddonna hard" :-)
  43.      3. Use WBPattern or NickPrefs WBPicture to load BGPic.pre
  44.      4. In your startup-sequence, before IPrefs or NickPrefs,
  45.         insert the lines:
  46.       delete >NIL: sys:prefs/presets/BGPic.pre
  47.       utilities:dbentry >NIL: dh0:dirdbs/WBPics.db random
  48.         pre="makelink sys:prefs/NickPrefs/wbpic.link " post=" hard" execute
  49.          (The last line was wrapped for readability)
  50.  
  51.  
  52.  Installation :
  53.  ~~~~~~~~~~~~
  54.  
  55.  1. Place the 3 programs somewhere on your path
  56.  2. Put the scripts somewhere on your path (s: comes to mind)
  57.  3. Execute the MakeDBPath script, specifying where you want
  58.     your database files to go. This script creates then
  59.     Env:db directory, sets up the Path variable there, and
  60.     duplicates the directory to EnvArc:, so it will be there
  61.     when you reboot.
  62.  4. Unpack and install upd, reading its documentation
  63.  
  64.  5. (Optional) Set up a cron to play sounds regularly, and
  65.     put the scripts on function keys using FKey. Set up a
  66.     function key with the upd Fade command to stop samples
  67.     if necessary.
  68.  
  69.  Maintenence :
  70.  ~~~~~~~~~~~
  71.  
  72. Directories change. It is necessary to reconstruct the databases
  73. occassionally. It is possible to automate this into a cron task,
  74. so that once a day, say at 1:15am, any databases you use are
  75. updated. Then again, you may only use the databases for non-essential
  76. tasks, so you can update them when you require.
  77.  
  78.  Environment Variables :
  79.  ~~~~~~~~~~~~~~~~~~~~~
  80.  
  81. These programs use a number of environment variables, which are kept
  82. in your Env:DB directory, which is created by the MakeDBPath script.
  83. These variables include a Path variable, which tells the programs where
  84. to look for your databases, a Seed variable, used by the Random Number
  85. generator, and initialised based on the system time, first time they
  86. are run. Also, each call to DBEntry sets up variables containing the
  87. last file name, and its position in the database.
  88.  
  89. -----------
  90.  
  91. MakeDirDB :
  92.  
  93. Makes a database containing all the file names in the specified
  94. directory/directories and their subdirectories.
  95.  
  96. Usage :
  97.  MakeDirDB DIR/M/A,DEST/A,PATTERN/K
  98.  
  99. Notes -
  100.  The database will contain any assigns specified in the Dir
  101. specification, but MakeDirDB cannot handle multiple path assigns.
  102. The assigns must be present when the database is referenced.
  103.  
  104. The Pattern defaults to #?, you might like to specify something
  105. like ~(#?.info) to exclude icons.
  106.  
  107. For example,
  108.   MakeDirDB Sounds: sys:DBDir/Sounds.db ~(#?.info)
  109.  
  110. -----------
  111.  
  112. FindDBEntry :
  113.  
  114. Finds all occurences of a pattern in specified directory database(s).
  115. Optionally do something with the found names.
  116.  
  117. Usage :
  118.  FindDBEntry  DIRDB/A/M,PAT=PATTERN/A,PRE=PREPEND/K,POST=APPEND/K,NOLINE/S,
  119.               EXECUTE/S,INFO/S,NOTINMEM/S,FULL/S,DIRS/S,NOFILES/S
  120.  
  121. Arguments :
  122.  
  123.  DIRDB/A/M :
  124.     Specifies the databases to search. See note later on
  125.     Environment Variables, and Paths.
  126.  
  127.  PAT=PATTERN/A :
  128.     Specifies the DOS pattern to search using.
  129.     By default, just searches filenames. You can specify directories in
  130.     the pattern, and even patterns in the directory part.
  131.     Examples
  132.        #?foo#?         matches anything with foo in its name.
  133.        #?bar#?/#?foo#? matches anything with foo in its name, which is in a
  134.                        directory containing bar in its name.
  135.  
  136.  PRE=PREPEND/K :
  137.     Specfies text to place before the result in the output.
  138.  POST=APPEND/K :
  139.     Specfies text to place after the result in the output.
  140.  
  141.     Examples :
  142.        prepend="type "
  143.        -- will type all matching files
  144.        pre="rx *"address play 'file' '" post="' '-S'*""
  145.        -- uses upd to play the resulting sound samples.
  146.           *'s are used to insert the quotes in a DOS commandline
  147.  
  148.  NOLINE/S :
  149.     When printing the results, don't put each on a new line.
  150.  
  151.  EXECUTE/S :
  152.     Instead of printing the results to the console, execute each line of
  153.     output (including pre and post strings) as DOS commands.
  154.  
  155.  INFO/S :
  156.     Output how many files are in the DataBase
  157.  
  158.  NOTINMEM/S :
  159.     Don't load the full database into memory before searching.
  160.     Greatly decreases speed, but saves memory, equal to
  161.     the size of the DB file.
  162.  
  163.  FULL/S :
  164.     Matches the pattern against the full file path, rather than just the
  165.     file name. This is done automatically if the pattern contains a '/'.
  166.     This option allows the pattern to match directory names, and so
  167.     anything in that directory.
  168.  
  169.  DIRS/S :
  170.     If a directory matches the pattern, it's full name is output.
  171.  
  172.  NOFILES/S :
  173.     Use with DIRS to search only for matching directories.
  174.  
  175.  
  176. -------
  177.  
  178. DBEntry :
  179.  
  180.  DBEntry DIRDB/A,PRE=PREPEND/K,POST=APPEND/K,NUM/N,RANDOM/S,NOLINE/S,
  181.          SPEC=SPECIFIC/N/K,EXECUTE/S,STARTRANGE/K/N,ENDRANGE/K/N,
  182.          LAST/S,NEXT/S,WRAP/S,INFO/S,INMEM/S,UNIQUE/S
  183.  
  184.  DIRDB/A/M :
  185.     Specifies the databases to search. See note later on
  186.     Environment Variables, and Paths.
  187.  
  188.  PRE=PREPEND/K :
  189.     Specfies text to place before the result in the output.
  190.  POST=APPEND/K :
  191.     Specfies text to place after the result in the output.
  192.  
  193.     Examples :
  194.        prepend="type "
  195.        -- will type all matching files
  196.        pre="rx *"address play 'file' '" post="' '-S'*""
  197.        -- uses upd to play the resulting sound samples.
  198.           *'s are used to insert the quotes in a DOS commandline
  199.  
  200.  NUM/N :
  201.     Specifies how many file names to output, see RANDOM
  202.  
  203.  RANDOM/S :
  204.     Choose the file names to output at random. If not specified,
  205.     DBEntry will just start at the first (or nth if SPECIFIC is
  206.     specified) and proceed linearly through the entries.
  207.     See UNIQUE.
  208.  
  209.  NOLINE/S :
  210.     When printing the results, don't put each on a new line.
  211.  
  212.  SPEC=SPECIFIC/N/K :
  213.     Specifies a starting point in the database, or the specific
  214.     entry to output if NUM is not specified or equals 1
  215.  
  216.  EXECUTE/S :
  217.     Instead of printing the results to the console, execute each line of
  218.     output (including pre and post strings) as DOS commands.
  219.  
  220.  STARTRANGE/K/N
  221.  ENDRANGE/K/N :
  222.     Limit the range to choose from with RANDOM
  223.  
  224.  LAST/S
  225.  NEXT/S :
  226.     Various information is stored in environment variables.
  227.     These options use that information to select the most recent entry,
  228.     or the one after that.
  229.     As DBs are kept in alphabetic order, by subdirectory, this can
  230.     play the next sound in a subtopic.
  231.  
  232.  WRAP/S :
  233.     If you specify a large number, or -1 to NUM, and there aren't that
  234.     many entries, wrap back to the start.
  235.  
  236.  INFO/S :
  237.     Output how many files are in the DataBase
  238.  
  239.  INMEM/S :
  240.     Load the full database into memory. Don't use for one-offs, but
  241.     if you are fetching multiple entries, saves time at the expense
  242.     of memory, equal to the size of the DB file.
  243.     Note the difference to the option for FindDBEntry.
  244.  
  245.  UNIQUE/S :
  246.     For use with RANDOM, and NUM > 1, makes sure entries are only
  247.     selected once each.
  248.  
  249.